home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 24 / AACD 24.iso / AACD / System / ReqToolsLib / Source / reqtools / rtgetstringa.c < prev    next >
Encoding:
C/C++ Source or Header  |  2001-07-02  |  5.7 KB  |  194 lines
  1.  
  2. /*
  3.     (C) 1999 - 2000 AROS - The Amiga Research OS
  4.     $Id: rtgetstringa.c,v 1.3 2000/11/26 16:53:48 stegerg Exp $
  5.  
  6.     Desc:
  7.     Lang: English
  8. */
  9.  
  10. #include <exec/types.h>
  11. #include <proto/exec.h>
  12. #include <proto/reqtools.h>
  13. #include <proto/intuition.h>
  14. #include <exec/libraries.h>
  15. #include <exec/memory.h>
  16. #include <libraries/reqtools.h>
  17. #include <aros/libcall.h>
  18.  
  19. #include "reqtools_intern.h"
  20. #include "general.h"
  21.  
  22. /*****************************************************************************
  23.  
  24.     NAME */
  25.  
  26.     AROS_LH5(ULONG, rtGetStringA,
  27.  
  28. /*  SYNOPSIS */
  29.  
  30.     AROS_LHA(UBYTE *, buffer, A1),
  31.     AROS_LHA(ULONG, maxchars, D0),
  32.     AROS_LHA(char *, title, A2),
  33.     AROS_LHA(struct rtReqInfo *, reqinfo, A3),
  34.     AROS_LHA(struct TagItem *, taglist, A0),
  35.  
  36. /*  LOCATION */
  37.  
  38.     struct ReqToolsBase *, ReqToolsBase, 12, ReqTools)
  39.  
  40. /*  FUNCTION
  41.     Puts up a string requester to get a line of text from the user. The
  42.     string present in 'buffer' upon entry will be displayed, ready to
  43.     be edited.
  44.  
  45.     'reqinfo' can be used to customize the requester. For greater
  46.     control use the tags listed below. The advantage of the rtReqInfo
  47.     structure is that it is global, where tags have to be specified
  48.     each function call. See libraries/reqtools.[hi] for a description
  49.     of the rtReqInfo structure.
  50.    
  51.     INPUTS
  52.     buffer - pointer to buffer to hold characters entered.
  53.     maxchars - maximum number of characters that fit in buffer
  54.         (EX-cluding the 0 to terminate the string !).
  55.     title - pointer to null terminated title of requester window.
  56.     reqinfo - pointer to a rtReqInfo structure allocated with
  57.         rtAllocRequest() or NULL.
  58.     taglist - pointer to a TagItem array.
  59.  
  60.     TAGS
  61.     RT_Window - see rtEZRequestA()
  62.  
  63.     RT_IDCMPFlags - see rtEZRequestA()
  64.  
  65.     RT_ReqPos - see rtEZRequestA()
  66.  
  67.     RT_LeftOffset - see rtEZRequestA()
  68.  
  69.     RT_TopOffset - see rtEZRequestA()
  70.  
  71.     RT_PubScrName - see rtEZRequestA()
  72.  
  73.     RT_Screen - see rtEZRequestA()
  74.  
  75.     RT_ReqHandler - see rtEZRequestA()
  76.  
  77.     RT_WaitPointer - see rtEZRequestA()
  78.  
  79.     RT_Underscore - [V38] see rtEZRequestA(). Only when you also use
  80.         the RTGS_GadFmt tag.
  81.  
  82.     RT_LockWindow - [V38] see rtEZRequestA()
  83.  
  84.     RT_ScreenToFront - [V38] see rtEZRequestA()
  85.  
  86.     RT_ShareIDCMP - [V38] see rtEZRequestA()
  87.  
  88.     RT_Locale - [V38] see rtEZRequestA()
  89.  
  90.     RT_IntuiMsgFunc - [V38] see rtEZRequestA()
  91.  
  92.     RT_TextAttr - [V38] see rtEZRequestA(). Note that under 1.2/1.3 the
  93.         string gadget's font will remain the screen font.
  94.  
  95.     RTGS_Width - (ULONG) Width of requester window in pixels. This is
  96.         only a suggestion. rtGetStringA() will not go below a certain
  97.         width.
  98.  
  99.     RTGS_AllowEmpty - (BOOL) If RTGS_AllowEmpty is TRUE an empty string
  100.         will also be accepted and returned. Defaults to FALSE, meaning
  101.         that if the user enters an empty string the requester will be
  102.         canceled.
  103.  
  104.     RTGS_GadFmt - (char *) [V38] Using this tag you can offer the user
  105.         severalresponses. See rtEZRequestA() for more information. Note
  106.         that selecting this gadget is considered a positive response so
  107.         the string in the gadget is copied to 'buffer'.
  108.  
  109.     RTGS_GadFmtArgs - (APTR) [V38] If you used formatting codes with
  110.         RTGS_GadFmt use this tag to pass the arguments.
  111.  
  112.     RTGS_Invisible - (BOOL) [V38] Using this tag you can switch on
  113.         invisible typing. Very useful if you need to get something like
  114.         a password from the user. It is strongly advised to use an
  115.         empty initial string or the user may get very confused! 
  116.         Default is FALSE.
  117.  
  118.     RTGS_BackFill - (BOOL) [V38] Backfill requester window with
  119.         pattern. Default TRUE.
  120.  
  121.     RTGS_TextFmt - (char *) [V38] Print these lines of text above the
  122.         gadget in the requester. Very useful to inform the user of what
  123.         he should enter. Most of the time you will also want to set the
  124.         GSREQF_CENTERTEXT flag. If you set the RTGS_BackFill tag to
  125.         FALSE _no_ recessed border will be placed around the text.
  126.         Formatting codes may be used in the string (see
  127.         RTGS_TextFmtArgs tag).
  128.  
  129.     RTGS_TextFmtArgs - (APTR) [V38] If you used formatting codes with
  130.         RTGS_TextFmt use this tag to pass the arguments.
  131.  
  132.     RTGS_Flags - (ULONG) [V38]
  133.  
  134.         GSREQF_CENTERTEXT - centers each line of text above the gadget
  135.             in the requester window. Should be generally set.
  136.  
  137.         GSREQF_HIGHLIGHTTEXT - Highlight text above the gadget. You
  138.             will normally only want to use this if you also turned off
  139.             the window backfilling.
  140.  
  141.     RESULT
  142.     ret - TRUE if user entered something, FALSE if not. If one of your
  143.         idcmp flags caused the requester to end 'ret' will hold this
  144.         flag. If you used the RTGS_GadFmt tag the return code will hold
  145.         the value of the response as with rtEZRequestA().
  146.  
  147.     NOTES
  148.     The contents of the buffer will NOT change if the requester is
  149.     aborted.
  150.  
  151.     Automatically adjusts the requester to the screen font.
  152.  
  153.     rtGetStringA() checks the pr_WindowPtr of your process to find the
  154.     screen to put the requester on.
  155.  
  156.     If you use the RTGS_GadFmt tag the return value is not always the
  157.     gadget the user selected. If the string gadget is empty and the
  158.     user presses the leftmost gadget (normally 'Ok') rtGetString() will
  159.     return 0 (FALSE)! If the string gadget is empty and the user
  160.     presses one of the other gadgets rtGetString() _will_ return its
  161.     value!  Important: 'buffer' will not be changed in either of these
  162.     cases.
  163.     If you set the RTGS_AllowEmpty tag to TRUE 'buffer' will always be
  164.     changed of course, and rtGetString() will always return the value
  165.     of the gadget pressed.
  166.  
  167.     EXAMPLE
  168.  
  169.     BUGS
  170.     none known
  171.  
  172.     SEE ALSO
  173.  
  174.     INTERNALS
  175.  
  176.     HISTORY
  177.  
  178. ******************************************************************************/
  179. {
  180.     AROS_LIBFUNC_INIT
  181.     
  182.     return GetString(buffer,
  183.                  maxchars,
  184.              title,
  185.              0,
  186.              NULL,
  187.              ENTER_STRING,
  188.              reqinfo,
  189.              taglist);
  190.              
  191.     AROS_LIBFUNC_EXIT
  192.     
  193. } /* rtgetstringa */
  194.